Skip to main content

Appointment Creation

In MediKIT, appointments are represented by the Appointment resource.

In order to create an appointment, the following data needs to be collected beforehand:

  • The practitioner's ID
  • The appointment type
  • The appointment start and end times

Appointment Types​

Available appointment types can be retrieved through the bookable appointment types ValueSet:

GET <TENANT_BASE_URL>/fhir/R4/ValueSet/BookableAppointmentType

Free slots​

Available appointment slots can be retrieved through the Slot resource. While all available slots can be retrieved without any additional input, it is possible and recommended to filter up-front so as to only retrieve slots the patient might be interested in.

GET <TENANT_BASE_URL>/fhir/R4/Slot

Available filters are:

  • service-category
    The category of the service to retrieve slots for.
  • start
    Retrieve only slots for which the start time matches the given value.
  • schedule
    The ID of the schedule to retrieve slots for.

Schedules​

Schedules indicate when healthcare professionals are available for specific types of appointments. Schedules can be retrieved through the Schedule resource.

GET <TENANT_BASE_URL>/fhir/R4/Schedule

Available filters are:

  • service-category
    The category of the service to retrieve schedules for.
  • date
    Retrieve only schedules for which the date matches the given value.

Creating an Appointment​

The creation of an appointment is done through a custom FHIR operation on the Appointment resource. Data should be POSTed to the endpoint, the body of which should be a Parameters resource containing the following parameters:

POST <TENANT_BASE_URL>/fhir/R4/Patient/<PATIENT_ID>/Appointment/$create
  • start
    The start time of the appointment.
  • schedule
    A Reference to the schedule to create the appointment in.
  • create-as-approved [Optional, default false]
    If set to true, the appointment will be created as booked, if false, the appointment will be created as proposed.
  • comment [Optional]
    A comment from the patient to be added to the appointment.

Retrieving Appointments​

Appointments for a given patient can be retrieved through the Appointment resource.

Search for appointments:

GET <TENANT_BASE_URL>/fhir/R4/Patient/<PATIENT_ID>/Appointment

Available filters are:

  • _id
    Retrieve only the appointment with the given ID.
  • status
    Retrieve only appointments with the given status (e.g. booked, proposed, cancelled).
  • date
    Retrieve only appointments for which the date matches the given value (supports ge, le modifiers).

Retrieve a single appointment by ID:

GET <TENANT_BASE_URL>/fhir/R4/Patient/<PATIENT_ID>/Appointment/<APPOINTMENT_ID>

Appointment Updates from Patient​

MediKIT allows for patients to update their attendance at an appointment. Currently, the only update available for patients is to cancel their attendance. This is done by POSTing an AppointmentResponse resource to the Appointment resource:

POST <TENANT_BASE_URL>/fhir/R4/Patient/<PATIENT_ID>/AppointmentResponse

{
    "appointment": {"reference": "Appointment/<APPOINTMENT_ID>"},
    "actor": {"reference": "Patient/<PATIENT_ID>"},
    "participantStatus": "declined"
}

Updates from Practice​

The practice can also update the appointment (either to booked from proposed, or to cancelled from booked or proposed). For this purpose, the patient-facing application should expose an API endpoint where AppointmentResponse resources can be POSTed. The request body should be similar to the one for updates from the patient, but with the following differences:

  • The actor should be the practitioner's ID.
  • The participantStatus can be accepted or declined.